Version: 12.10.0

Azure Container Registry

Alt text

Registry

A container registry is a service that stores and distributes container images and related artifacts. Docker Hub is an example of a public container registry that serves as a general catalog of Docker container images. Azure Container Registry provides users with direct control of their container content, with integrated authentication, geo-replication supporting global distribution and reliability for network-close deployments, virtual network configuration with Private Link, tag locking, and many other enhanced features.

In addition to Docker-compatible container images, Azure Container Registry supports a range of content artifacts including Helm charts and Open Container Initiative (OCI) image formats.

Repository

A repository is a collection of container images or other artifacts in a registry that have the same name, but different tags. For example, the following three images are in the acr-helloworld repository:

acr-helloworld:latest
acr-helloworld:v1
acr-helloworld:v2

Repository names can also include namespaces. Namespaces allow you to identify related repositories and artifact ownership in your organization by using forward slash-delimited names. However, the registry manages all repositories independently, not as a hierarchy. For example:

marketing/campaign10-18/web:v2
marketing/campaign10-18/api:v3
marketing/campaign10-18/email-sender:v2
product-returns/web-submission:20180604
product-returns/legacy-integrator:20180715

Repository names can only include lowercase alphanumeric characters, periods, dashes, underscores, and forward slashes.

Artifact A container image or other artifact within a registry is associated with one or more tags, has one or more layers, and is identified by a manifest. Understanding how these components relate to each other can help you manage your registry effectively.

Tag The tag for an image or other artifact specifies its version. A single artifact within a repository can be assigned one or many tags, and may also be "untagged." That is, you can delete all tags from an image, while the image's data (its layers) remain in the registry.

The repository (or repository and namespace) plus a tag defines an image's name. You can push and pull an image by specifying its name in the push or pull operation. The tag latest is used by default if you don't provide one in your Docker commands.

How you tag container images is guided by your scenarios to develop or deploy them. For example, stable tags are recommended for maintaining your base images, and unique tags for deploying images. For more information, see Recommendations for tagging and versioning container images.

Layer Container images and artifacts are made up of one or more layers. Different artifact types define layers differently. For example, in a Docker container image, each layer corresponds to a line in the Dockerfile that defines the image:

Alt text

Artifacts in a registry share common layers, increasing storage efficiency. For example, several images in different repositories might have a common ASP.NET Core base layer, but only one copy of that layer is stored in the registry. Layer sharing also optimizes layer distribution to nodes, with multiple artifacts sharing common layers. If an image already on a node includes the ASP.NET Core layer as its base, the subsequent pull of a different image referencing the same layer doesn't transfer the layer to the node. Instead, it references the layer already existing on the node.

To provide secure isolation and protection from potential layer manipulation, layers are not shared across registries.

Manifest

Each container image or artifact pushed to a container registry is associated with a manifest. The manifest, generated by the registry when the content is pushed, uniquely identifies the artifacts and specifies the layers.

A basic manifest for a Linux hello-world image looks similar to the following

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 1510,
    "digest": "sha256:fbf289e99eb9bca977dae136fbe2a82b6b7d4c372474c9235adc1741675f587e"
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 977,
      "digest": "sha256:2c930d010525941c1d56ec53b97bd057a67ae1865eebf042686d2a2d18271ced"
    }
  ]
}

Push by tag Examples:

docker push myregistry.azurecr.io/samples/myimage:20210106

docker push myregistry.azurecr.io/marketing/email-sender

Pull by tag Example:

docker pull myregistry.azurecr.io/marketing/campaign10-18/email-sender:v2

Pull by manifest digest Example:

docker pull myregistry.azurecr.io/acr-helloworld@sha256:0a2e01852872580b2c2fea9380ff8d7b637d3928783c55beb3f21a6e58d5d108

Log in to a registry

Alt text

There are several ways to authenticate to your private container registry.

The recommended method when working in a command line is with the Azure CLI command az acr login. For example, to access a registry named myregistry, sign in the Azure CLI and then authenticate to your registry:

az login
az acr login --name myregistry

You can also log in with docker login. For example, you might have assigned a service principal to your registry for an automation scenario. When you run the following command, interactively provide the service principal appID (username) and password when prompted.

docker login myregistry.azurecr.io

Log in to a registry​

Log in to a registry